Molecule

작성자

익명

작성일

2026.08.04

조회수

버전

Molecule

1. 개요

Molecule은 인프라 자동화 도구인 Ansible 롤(Role)과 플레이북(Playbook)을 테스트하기 위해 설계된 오픈소스 테스트 프레임워크이다.

Kubernetes 환경을 포함한 다양한 인프라 환경에서 설정 관리 코드가 의도한 대로 동작하는지 검증하는 것을 목적으로 하며, 인프라의 생성부터 설정 적용, 검증, 삭제에 이르는 전체 라이프사이클을 자동화하여 '인프라로서의 코드(IaC, Infrastructure as Code)'의 신뢰성을 확보하는 핵심 가치를 제공한다.

2. 주요 특징 및 작동 원리

Molecule은 선언적인 테스트 프로세스를 통해 인프라의 상태를 관리한다. 단순히 스크립트를 실행하는 것이 아니라, 정의된 시나리오에 따라 인프라를 프로비저닝하고 상태를 수렴시킨 뒤 검증하는 정형화된 라이프사이클을 따른다.

테스트 라이프사이클 단계

단계	명칭	목적	상태 변화 및 설명
Init	초기화	테스트 환경 준비	필요한 설정 파일 및 디렉토리 구조 생성
Create	생성	프로비저너(Provisioner) 실행	Docker 컨테이너나 VM 등 테스트 대상 인스턴스 생성
Converge	수렴	설정 적용	Ansible 롤을 실행하여 대상 인스턴스를 원하는 상태로 변경
Idempotence	멱등성 검사	중복 실행 검증	동일한 설정을 다시 적용했을 때 변경 사항이 없는지 확인
Verify	검증	결과 확인	Testinfra, Goss 등을 통해 실제 서비스 포트, 파일, 패키지 상태 확인
Destroy	삭제	자원 회수	테스트에 사용된 인스턴스 및 네트워크 자원 삭제

3. 지원 환경 및 통합 도구

Molecule은 특정 환경에 종속되지 않도록 다양한 프로비저너(Provisioner)와 검증 도구(Verifier)를 플러그인 형태로 지원한다.

지원 도구 및 관계

프로비저너 (Provisioners): 인프라 생성 도구
- Docker: 가장 널리 사용되며, 가볍고 빠른 컨테이너 기반 환경 제공.
- Delegated: 사용자가 직접 정의한 인프라(예: 클라우드 VM)를 사용.
- Vagrant: 가상 머신 기반의 격리된 환경 제공.
검증 도구 (Verifiers): 설정이 올바르게 적용되었는지 확인하는 도구
- Testinfra: Python 기반의 도구로, SSH를 통해 서버 상태를 검증.
- Goss: YAML 기반의 설정 파일로 빠르게 상태를 확인하는 경량 도구.
- Ansible: Ansible 자체의 assert 모듈 등을 사용하여 검증.

타 테스트 도구와의 비교

비교 항목	Molecule	Ansible-Lint	Pytest (단독)
주요 목적	통합 테스트 및 라이프사이클 관리	정적 코드 분석 (문법/스타일)	일반적인 소프트웨어 단위 테스트
실행 방식	실제 인프라 생성 후 실행	코드 텍스트 분석	코드 로직 실행
검증 대상	최종 인프라 상태 (State)	코드 작성 규칙 (Convention)	함수/클래스 출력값
특징	멱등성 검증 가능	실행 없이 빠르게 확인 가능	범용적이나 인프라 제어 기능 부족

4. 설치 및 기본 설정

Molecule은 Python 패키지 관리자인 <a href="/doc/%EA%B8%B0%EC%88%A0/%ED%94%84%EB%A1%9C%EA%B7%B8%EB%9E%98%EB%B0%8D/%ED%8C%A8%ED%82%A4%EC%A7%80%20%EA%B4%80%EB%A6%AC%EC%9E%90/pip" class="wiki-link wiki-link-missing">pip</a>를 통해 설치한다. 최신 버전의 Molecule은 코어 기능과 플러그인이 분리된 구조이므로, 코어 패키지 설치 후 사용하고자 하는 환경에 맞는 플러그인을 반드시 추가로 설치해야 한다.

설치 방법

# Molecule 코어 설치
pip install molecule

# 사용하려는 프로비저너 및 검증 도구 플러그인 설치 (예: Docker 사용 시)
pip install "molecule-plugins[docker]"

`molecule.yml` 설정 예시

molecule.yml은 테스트 환경의 청사진 역할을 하는 핵심 설정 파일이다.

# molecule/default/molecule.yml
dependency:
  name: galaxy
driver:
  name: docker # 프로비저너 지정

platforms:
  - name: ubuntu-test-node
    image: geerlingguy/ubuntu2204:latest # 테스트에 사용할 베이스 이미지
    pre_build:
      - ansible_python_interpreter: /usr/bin/python3

provisioner:
  name: ansible # 설정 적용 도구

verifier:
  name: testinfra # 검증 도구 지정

5. 시나리오(Scenario) 개념

Molecule은 '시나리오(Scenario)'라는 단위로 테스트 환경을 관리한다. 시나리오는 특정 OS 버전, 특정 설정 조합 등 테스트하고자 하는 하나의 독립된 환경 정의를 의미한다.

구조: molecule/<scenario_name>/ 디렉토리 구조를 가진다. (예: molecule/default, molecule/ubuntu2204, molecule/rocky9)
다중 환경 테스트: 여러 시나리오를 구성하면 동일한 Ansible 롤이 다양한 OS나 환경에서 동일하게 동작하는지 교차 검증할 수 있다.

실행 방법: 특정 시나리오를 지정하여 명령어를 실행할 수 있다.

    molecule run <scenario_name> <command>
    # 예: molecule run ubuntu2204 converge

6. 테스트 워크플로우 (사용법)

Molecule은 개별 명령어를 통해 단계별로 실행하거나, test 명령어로 전체 프로세스를 한 번에 수행할 수 있다.

주요 명령어 실행 흐름

# 0. 테스트 시나리오 초기 구조 생성 (최초 1회)
molecule init scenario

# 1. 테스트 인스턴스 생성
molecule create

# 2. Ansible 롤 적용 (수렴)
molecule converge

# 3. 멱등성 테스트 (두 번째 실행 시 변경 사항이 없어야 함)
molecule idempotence

# 4. 설정 상태 검증
molecule verify

# 5. 인스턴스 삭제
molecule destroy

# [종합] 위 모든 과정을 순차적으로 자동 실행
molecule test

`molecule test` 실행 로그 예시

전체 프로세스를 실행하면 다음과 같은 흐름의 로그가 출력된다.

$ molecule test
...
Creating instances...
  - ubuntu-test-node: SUCCESS
Converging...
  - ubuntu-test-node: SUCCESS
Checking for idempotence...
  - ubuntu-test-node: SUCCESS
Verifying...
  - ubuntu-test-node: SUCCESS
Destroying instances...
  - ubuntu-test-node: SUCCESS
Test complete!

실제 테스트 시나리오 사례: Nginx 웹 서버 설치 롤

시나리오: Nginx 패키지를 설치하고 80번 포트가 활성화되었는지 확인한다.
Converge: Ansible 롤이 apt install nginx를 수행하고 서비스를 시작함.

Verify (Testinfra 코드):

    import pytest

    def test_nginx_is_installed(host):
        nginx = host.package("nginx")
        assert nginx.is_installed

    def test_nginx_running_and_listening(host):
        socket = host.socket("tcp://0.0.0.0:80")
        assert socket.is_listening

    def test_nginx_config_file_exists(host):
        config = host.file("/etc/nginx/nginx.conf")
        assert config.exists
        assert config.user == "root"

7. 베스트 프랙티스 및 주의사항

효율적인 테스트를 위한 팁

경량 이미지 사용: 테스트 속도를 높이기 위해 가능한 한 작은 베이스 이미지를 사용하라.
멱등성 확보: molecule idempotence 단계에서 실패한다면, Ansible 태스크에 changed_when: false 또는 적절한 조건문을 추가하여 불필요한 변경이 일어나지 않도록 수정해야 한다.
독립적 테스트: 각 테스트 시나리오는 서로 의존성이 없어야 하며, molecule destroy 후 다시 create 했을 때 동일한 결과가 나와야 한다.

CI/CD 파이프라인 통합 예시 (GitHub Actions)

Molecule은 CLI 기반으로 동작하므로 CI/CD 파이프라인에 쉽게 통합할 수 있다.

name: Ansible Role Test
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'
      - name: Install Molecule
        run: |
          pip install molecule "molecule-plugins[docker]"
      - name: Run Molecule Test
        run: |
          molecule test

주의사항 및 오류 해결

권한 문제: Docker 프로비저너 사용 시 CI 환경에서 Docker 데몬에 접근할 수 있는 권한이 있는지 확인해야 한다.
Python 버전 불일치: 호스트 머신의 Python 버전과 테스트 대상 인스턴스(Container) 내부의 Python 버전이 다를 경우 ansible_python_interpreter 설정을 통해 명시적으로 경로를 지정해야 한다.
네트워크 타임아웃: 외부 저장소에서 패키지를 다운로드하는 과정에서 네트워크 지연이 발생할 경우 molecule converge 단계에서 타임아웃이 발생할 수 있으므로, 필요시 프록시 설정이나 로컬 미러를 활용한다.

📝 마크다운 원본

이 문서의 마크다운 원본 내용입니다.

# Molecule

## 1. 개요
**Molecule**은 인프라 자동화 도구인 Ansible 롤(Role)과 플레이북(Playbook)을 테스트하기 위해 설계된 오픈소스 테스트 프레임워크이다. 

Kubernetes 환경을 포함한 다양한 인프라 환경에서 설정 관리 코드가 의도한 대로 동작하는지 검증하는 것을 목적으로 하며, 인프라의 생성부터 설정 적용, 검증, 삭제에 이르는 전체 라이프사이클을 자동화하여 '인프라로서의 코드(IaC, Infrastructure as Code)'의 신뢰성을 확보하는 핵심 가치를 제공한다.

## 2. 주요 특징 및 작동 원리
Molecule은 선언적인 테스트 프로세스를 통해 인프라의 상태를 관리한다. 단순히 스크립트를 실행하는 것이 아니라, 정의된 시나리오에 따라 인프라를 프로비저닝하고 상태를 수렴시킨 뒤 검증하는 정형화된 라이프사이클을 따른다.

### 테스트 라이프사이클 단계
| 단계 | 명칭 | 목적 | 상태 변화 및 설명 |
| :--- | :--- | :--- | :--- |
| **Init** | 초기화 | 테스트 환경 준비 | 필요한 설정 파일 및 디렉토리 구조 생성 |
| **Create** | 생성 | 프로비저너(Provisioner) 실행 | Docker 컨테이너나 VM 등 테스트 대상 인스턴스 생성 |
| **Converge** | 수렴 | 설정 적용 | Ansible 롤을 실행하여 대상 인스턴스를 원하는 상태로 변경 |
| **Idempotence** | 멱등성 검사 | 중복 실행 검증 | 동일한 설정을 다시 적용했을 때 변경 사항이 없는지 확인 |
| **Verify** | 검증 | 결과 확인 | Testinfra, Goss 등을 통해 실제 서비스 포트, 파일, 패키지 상태 확인 |
| **Destroy** | 삭제 | 자원 회수 | 테스트에 사용된 인스턴스 및 네트워크 자원 삭제 |

## 3. 지원 환경 및 통합 도구
Molecule은 특정 환경에 종속되지 않도록 다양한 프로비저너(Provisioner)와 검증 도구(Verifier)를 플러그인 형태로 지원한다.

### 지원 도구 및 관계
*   **프로비저너 (Provisioners):** 인프라 생성 도구
    *   **Docker:** 가장 널리 사용되며, 가볍고 빠른 컨테이너 기반 환경 제공.
    *   **Delegated:** 사용자가 직접 정의한 인프라(예: 클라우드 VM)를 사용.
    *   **Vagrant:** 가상 머신 기반의 격리된 환경 제공.
*   **검증 도구 (Verifiers):** 설정이 올바르게 적용되었는지 확인하는 도구
    *   **Testinfra:** Python 기반의 도구로, SSH를 통해 서버 상태를 검증.
    *   **Goss:** YAML 기반의 설정 파일로 빠르게 상태를 확인하는 경량 도구.
    *   **Ansible:** Ansible 자체의 `assert` 모듈 등을 사용하여 검증.

### 타 테스트 도구와의 비교
| 비교 항목 | Molecule | Ansible-Lint | Pytest (단독) |
| :--- | :--- | :--- | :--- |
| **주요 목적** | 통합 테스트 및 라이프사이클 관리 | 정적 코드 분석 (문법/스타일) | 일반적인 소프트웨어 단위 테스트 |
| **실행 방식** | 실제 인프라 생성 후 실행 | 코드 텍스트 분석 | 코드 로직 실행 |
| **검증 대상** | 최종 인프라 상태 (State) | 코드 작성 규칙 (Convention) | 함수/클래스 출력값 |
| **특징** | 멱등성 검증 가능 | 실행 없이 빠르게 확인 가능 | 범용적이나 인프라 제어 기능 부족 |

## 4. 설치 및 기본 설정
Molecule은 Python 패키지 관리자인 `pip`를 통해 설치한다. 최신 버전의 Molecule은 코어 기능과 플러그인이 분리된 구조이므로, 코어 패키지 설치 후 사용하고자 하는 환경에 맞는 플러그인을 반드시 추가로 설치해야 한다.

### 설치 방법
```bash
# Molecule 코어 설치
pip install molecule

# 사용하려는 프로비저너 및 검증 도구 플러그인 설치 (예: Docker 사용 시)
pip install "molecule-plugins[docker]"
```

### `molecule.yml` 설정 예시
`molecule.yml`은 테스트 환경의 청사진 역할을 하는 핵심 설정 파일이다.

```yaml
# molecule/default/molecule.yml
dependency:
  name: galaxy
driver:
  name: docker # 프로비저너 지정

platforms:
  - name: ubuntu-test-node
    image: geerlingguy/ubuntu2204:latest # 테스트에 사용할 베이스 이미지
    pre_build:
      - ansible_python_interpreter: /usr/bin/python3

provisioner:
  name: ansible # 설정 적용 도구

verifier:
  name: testinfra # 검증 도구 지정
```

## 5. 시나리오(Scenario) 개념
Molecule은 **'시나리오(Scenario)'**라는 단위로 테스트 환경을 관리한다. 시나리오는 특정 OS 버전, 특정 설정 조합 등 테스트하고자 하는 하나의 독립된 환경 정의를 의미한다.

*   **구조:** `molecule/<scenario_name>/` 디렉토리 구조를 가진다. (예: `molecule/default`, `molecule/ubuntu2204`, `molecule/rocky9`)
*   **다중 환경 테스트:** 여러 시나리오를 구성하면 동일한 Ansible 롤이 다양한 OS나 환경에서 동일하게 동작하는지 교차 검증할 수 있다.
*   **실행 방법:** 특정 시나리오를 지정하여 명령어를 실행할 수 있다.
    ```bash
    molecule run <scenario_name> <command>
    # 예: molecule run ubuntu2204 converge
    ```

## 6. 테스트 워크플로우 (사용법)
Molecule은 개별 명령어를 통해 단계별로 실행하거나, `test` 명령어로 전체 프로세스를 한 번에 수행할 수 있다.

### 주요 명령어 실행 흐름
```bash
# 0. 테스트 시나리오 초기 구조 생성 (최초 1회)
molecule init scenario

# 1. 테스트 인스턴스 생성
molecule create

# 2. Ansible 롤 적용 (수렴)
molecule converge

# 3. 멱등성 테스트 (두 번째 실행 시 변경 사항이 없어야 함)
molecule idempotence

# 4. 설정 상태 검증
molecule verify

# 5. 인스턴스 삭제
molecule destroy

# [종합] 위 모든 과정을 순차적으로 자동 실행
molecule test
```

### `molecule test` 실행 로그 예시
전체 프로세스를 실행하면 다음과 같은 흐름의 로그가 출력된다.
```text
$ molecule test
...
Creating instances...
  - ubuntu-test-node: SUCCESS
Converging...
  - ubuntu-test-node: SUCCESS
Checking for idempotence...
  - ubuntu-test-node: SUCCESS
Verifying...
  - ubuntu-test-node: SUCCESS
Destroying instances...
  - ubuntu-test-node: SUCCESS
Test complete!
```

### 실제 테스트 시나리오 사례: Nginx 웹 서버 설치 롤
1.  **시나리오:** Nginx 패키지를 설치하고 80번 포트가 활성화되었는지 확인한다.
2.  **Converge:** Ansible 롤이 `apt install nginx`를 수행하고 서비스를 시작함.
3.  **Verify (Testinfra 코드):**
    ```python
    import pytest

    def test_nginx_is_installed(host):
        nginx = host.package("nginx")
        assert nginx.is_installed

    def test_nginx_running_and_listening(host):
        socket = host.socket("tcp://0.0.0.0:80")
        assert socket.is_listening

    def test_nginx_config_file_exists(host):
        config = host.file("/etc/nginx/nginx.conf")
        assert config.exists
        assert config.user == "root"
    ```

## 7. 베스트 프랙티스 및 주의사항

### 효율적인 테스트를 위한 팁
*   **경량 이미지 사용:** 테스트 속도를 높이기 위해 가능한 한 작은 베이스 이미지를 사용하라.
*   **멱등성 확보:** `molecule idempotence` 단계에서 실패한다면, Ansible 태스크에 `changed_when: false` 또는 적절한 조건문을 추가하여 불필요한 변경이 일어나지 않도록 수정해야 한다.
*   **독립적 테스트:** 각 테스트 시나리오는 서로 의존성이 없어야 하며, `molecule destroy` 후 다시 `create` 했을 때 동일한 결과가 나와야 한다.

### CI/CD 파이프라인 통합 예시 (GitHub Actions)
Molecule은 CLI 기반으로 동작하므로 CI/CD 파이프라인에 쉽게 통합할 수 있다.

```yaml
name: Ansible Role Test
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'
      - name: Install Molecule
        run: |
          pip install molecule "molecule-plugins[docker]"
      - name: Run Molecule Test
        run: |
          molecule test
```

### 주의사항 및 오류 해결
*   **권한 문제:** Docker 프로비저너 사용 시 CI 환경에서 Docker 데몬에 접근할 수 있는 권한이 있는지 확인해야 한다.
*   **Python 버전 불일치:** 호스트 머신의 Python 버전과 테스트 대상 인스턴스(Container) 내부의 Python 버전이 다를 경우 `ansible_python_interpreter` 설정을 통해 명시적으로 경로를 지정해야 한다.
*   **네트워크 타임아웃:** 외부 저장소에서 패키지를 다운로드하는 과정에서 네트워크 지연이 발생할 경우 `molecule converge` 단계에서 타임아웃이 발생할 수 있으므로, 필요시 프록시 설정이나 로컬 미러를 활용한다.

AI 생성 콘텐츠 안내

이 문서는 AI 모델(gemma-4-31b)에 의해 생성된 콘텐츠입니다.

주의사항: AI가 생성한 내용은 부정확하거나 편향된 정보를 포함할 수 있습니다. 중요한 결정을 내리기 전에 반드시 신뢰할 수 있는 출처를 통해 정보를 확인하시기 바랍니다.

위키너와나

Molecule

Molecule

1. 개요

2. 주요 특징 및 작동 원리

테스트 라이프사이클 단계

3. 지원 환경 및 통합 도구

지원 도구 및 관계

타 테스트 도구와의 비교

4. 설치 및 기본 설정

설치 방법

`molecule.yml` 설정 예시

5. 시나리오(Scenario) 개념

6. 테스트 워크플로우 (사용법)

주요 명령어 실행 흐름

`molecule test` 실행 로그 예시

실제 테스트 시나리오 사례: Nginx 웹 서버 설치 롤

7. 베스트 프랙티스 및 주의사항

효율적인 테스트를 위한 팁

CI/CD 파이프라인 통합 예시 (GitHub Actions)

주의사항 및 오류 해결

📝 마크다운 원본

🤔 AI의 사고 과정

이 AI 생성 콘텐츠가 도움이 되었나요?

Molecule

1. 개요

2. 주요 특징 및 작동 원리

테스트 라이프사이클 단계

3. 지원 환경 및 통합 도구

지원 도구 및 관계

타 테스트 도구와의 비교

4. 설치 및 기본 설정

설치 방법

molecule.yml 설정 예시

5. 시나리오(Scenario) 개념

6. 테스트 워크플로우 (사용법)

주요 명령어 실행 흐름

molecule test 실행 로그 예시

실제 테스트 시나리오 사례: Nginx 웹 서버 설치 롤

7. 베스트 프랙티스 및 주의사항

효율적인 테스트를 위한 팁

CI/CD 파이프라인 통합 예시 (GitHub Actions)

주의사항 및 오류 해결

📝 마크다운 원본

🤔 AI의 사고 과정

이 AI 생성 콘텐츠가 도움이 되었나요?

`molecule.yml` 설정 예시

`molecule test` 실행 로그 예시